home *** CD-ROM | disk | FTP | other *** search
/ George Foreman's Interac…ng, Barbeque & Rotisserie / George Foreman's Interactive Guide to Grilling, Barbeque, and Rotisserie.iso / install.exe / Windows / resource / jre / lib / jvm.jcov.txt < prev    next >
Text File  |  2002-11-05  |  5KB  |  120 lines
  1. version : @(#)jvm.jcov.txt    1.3 00/11/02
  2.         JCOV support in JDK1.3
  3.  
  4. Up to JDK1.2.x Jcov runtime support has been an integral part of the
  5. debug version of the Javasoft's JVM, therefore it could not work with
  6. any other JVMs. In JDK1.3 all Jcov support was isolated in a separate
  7. library and implemented basing upon the Java Virtual Machine Profiler
  8. Interface (JVMPI), so it theoretically can work with any JVM that
  9. support JVMPI. This library is loaded by a JVM at its startup, if the
  10. -Xrunjcov option is specified. For more information about how JVM finds
  11. and loads libraries passed via the -Xrun<libname> JVM's option, please
  12. consult JVMPI docs.
  13.  
  14. usage:
  15.  
  16. java [other java options] -Xrunjcov[:][help]|[<option>=<value>, ...] classname
  17.  
  18. where <option> is the name of an option, <value> is its value. The
  19. recognized options are :
  20.  
  21. include=<class name prefix>
  22.     makes Jcov profile only those classes whose names begin with given
  23.     class name prefix. This option may be specified multiple times - in
  24.     this case class name must satisfy at least one of the class name
  25.     prefixes to be profiled.
  26. exclude=<class name prefix>
  27.     tells Jcov not to profile classes whose names begin with given
  28.     class name prefix. This option may be given multiple times - if a
  29.     class name satisfies at least one of the class name prefixes then
  30.     it will not be profiled.
  31. type=<value>
  32.     value can be either B or M. Sets jcov data gathering mode : in B
  33.     mode method/block/branch coverage data is gathered, in M only
  34.     method coverage data is gathered. Default value is B.
  35. file=<filename>
  36.     specifies savefile name, default - java.jcov.
  37. caller_include=<class name prefix>
  38.     gather coverage data only for methods invoked from the specified
  39.     class or classes beloning to the specified package; the option can be
  40.     used multiple times; class or package names should use '.' as a
  41.     package separator
  42. caller_exclude=<class name prefix>
  43.     gather coverage data only for methods invoked *not* from the specified
  44.     class or classes *not* beloning to the specified package; the option can
  45.     be used multiple times; class or package names should use '.' as a
  46.     package separator
  47. abstract_methods=<on|off>
  48.     store/do not store jcov data for abstract methods; default is 'off'
  49. options_file=<filename>
  50.     specifies where to read options from; (caller_)include/(caller_)exclude
  51.     options values read from the file are added to those, specified in the
  52.     command line
  53.  
  54.  
  55. Example 1.
  56.     > java -classic -Xrunjcov class
  57.  
  58. This command will make Jcov profile all loaded classes which have the
  59. CoverageTable class attribute (i.e. all loaded classes which had been
  60. compiled with the -Xjcov compiler option) and save method/block/branch
  61. coverage data to a file named java.jcov in current directory.
  62.  
  63. Example 2.
  64.     > java -classic \
  65.       -Xrunjcov:include=java,exclude=java.io,type=M,file=/tmp/sys.jcov \
  66.       <class>
  67.  
  68. This command will make Jcov profile all classes from the java package
  69. and its subpackages except java.lang and java.io, only method coverage
  70. statistics will be gathered and saved to a file named sys.jcov' in the
  71. /tmp directory.
  72.  
  73. Example 3.
  74.     > cat options
  75.     include=java.
  76.     include=javax.
  77.     include=org.
  78.     caller_include=javasoft.sqe.tests.
  79.     file=/tmp/api.jcov
  80.     abstract_methods=on
  81.     type=M
  82.     > java -classic -Xrunjcov:options_file=options <class>
  83.  
  84. The first command shows the contents of the 'options' file where Jcov options
  85. are taken from. The second command will make jcov profile all standard API classes
  86. that will be loaded during execution of the <class>. Method coverage information
  87. will be gathered for all methods (including abstract), but execution counters will
  88. be incremented only for methods invoked from classes belonging to 'javasoft.sqe.tests'
  89. package.
  90.  
  91. Note that
  92.  
  93.   1.JVM must not be run in debug mode (-Xdebug option must not be
  94.     specified), since Jcov cannot work correctly in this
  95.     JVM's mode.  
  96.   2.When gathered data is saved to an existing Jcov data
  97.     file, then it is merged (on per-class basis) with the corresponding
  98.     data found in the file. If the data types of two classes being
  99.     merged don't match, then both classes are saved in the resulting
  100.     jcov data file.
  101.   3.(JDK 1.2, early versions of JDK1.3) For Jcov to work correctly any JIT 
  102.     compiler must be turned off (for example, by specifying the
  103.     -Djava.compiler=NONE JVM's option)
  104.   4.If a class or an interface contains only abstract methods then it will
  105.     not be profiled at all (i.e. no code coverage data will be gathered
  106.     for it). 
  107.   5.Only non-abstract methods are profiled.
  108.   6.If data gathering mode is set to B then those classes, having no
  109.     CoverageTable class attribute (i.e. compiled without -Xjcov option),
  110.     will not be profiled.
  111.   7.For Jcov to be able to gather block/branch coverage data for a certain
  112.     class, this class must have CoverageTable class attribute. This can be
  113.     achived by compiling this class with the -prof=jcov (JDK1.1 - JDK
  114.     1.1.x) option or the -Xjcov (JDK1.2 - JDK 1.2.x) option.
  115.   8.In JDK 1.3.0 -classic JVM option should be specified for Jcov to
  116.     work correctly since HotSpot there does not fully implement the JVMPI
  117.     interface Jcov is based on. JDK 1.3.1 (as of build 06) works fine without
  118.     this option, but -XX:+EnableJVMPIInstructionStartEvent option should
  119.     additionally be specified.
  120.